Merge PR #251 before this one, as it branches from that implementation.

Note

Hello, future developer. I am the developer who opened this PR and the corresponding issue. As my directed study is now coming to an end, I will not be able to finish this feature off for review. As such, I would like to take the opportunity in this description to thoroughly communicate everything that's been done and yet to be done.

Description

This feature adds onto the existing insights implementation to allow administrators and professors to see how their course's statistics might compare to the same course from a previous semester or another section of the same term. This would also allow these users to view the general trends over many semesters (once we have more). Below, I outlined the steps I have already taken and the steps I would have taken to finish this feature, given more time. I hope this can serve more as a useful guide than an instruction manual, so please feel free to implement this feature differently if you truly think that is best.

• To facilitate this in the backend, the idea is to use a new table called "super_course_model" and add foreign keys to all existing courses so that there exists an identifier that for each course's clones (as well as non-clones that are still of the same course).

• After the creation of this table, modifications to the clone implementation of the backend are necessary to automatically attach clones to the same supercourse as the original. Modifications also need to be made to the course creation and modification endpoints to generate super-course entries for newly created courses.

  • I have added a rough implementation that checks and matches course names to super-course names, as there is no other way to identify the courses already in production other than by their names. A more deterministic approach should be pursued once all production courses are assigned a super-course.
  • Look at course.service.ts for the cloneCourses function and organization.controller.ts for the course creation and modification routes which query to update the super-course table for my rough implementation to update production. Both routes are in the /server directory (the backend service).

• Then, modifications need to be made to the course settings page to allow select trusted users (ie, organization admin) to change a course's supercourse should the need arise.

• Now, you can focus on the insights themselves, using the supercourse model to query for any and all course entries of the same course.

  • This is where I ended my development, so I have added stubs for two insights (total questions across semesters and across sections). Thinking on this now, combining all multi-course insights into one type (you can sort your statistics by type in the frontend) might be better (total questions across semesters in the x-axis to represent semesters since the first --including summer--, and across sections via multiple lines in certain semesters to fit all total questions information for a particular course in one chart instead of two). Please feel free to implement whichever one you think is best. Other than that, you can look to the existing insights for inspiration or ask the team about other potential insights that might be useful to display here.
  • These insight definitions can be found in: insight-objects.ts in the /server directory (the backend service).

• Once the desired chart objects are created, you can move onto the frontend service and ensure that the charts render as desired on the page.

  • I have already defined two insight types here: across-semesters and across-sections. Again, if you would like to blend these into one type, that works too and won't involve much refactoring (simply modify the const InsightCategories array found in the index.ts file of the common package, and then modify the insightMenuItems object in InsightsPageMenu.tsx of the frontend to match).

• Finally, tests will have to be written to test the super-course interactions in the backend for cloning, creating, and modifying courses. Also, write tests to verify the results of the new insights you have created.

• Other Tips

  • You may find PAT TODO: comments throughout these files. These are no different than normal TODOs other than that they are relevant to this PR and should be addressed before this PR is merged. They served as personal reminders for lapses of less development where I may have forgotten what I was working on.

Closes #256

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update
• This requires a run of yarn install
• This change requires an addition/change to the production .env variables. These changes are below:
• This change requires developers to add new .env variables. The file and variables needed are below:
• This change requires a database query to update old data on production. This query is below:

How Has This Been Tested?

Please describe how you tested this PR (both manually and with tests)
Provide instructions so we can reproduce.

• Test A
• Test B

Checklist:

• I have performed a self-review of my own code
• I have commented my code where needed
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any work that this PR is dependent on has been merged into the main branch
• Any UI changes have been checked to work on desktop, tablet, and mobile